Web-Resolver

Der Web-Resolver löst Anruferrufnummern über eine HTTP(S)-Abfrage gegen Ihre Anwendung auf. Reverse Lookup PRO ist dabei der Client — Ihre Anwendung stellt den Server-Endpunkt bereit, der eine Rufnummer als Anfrage entgegennimmt und eine Textantwort (JSON, XML, HTML oder Klartext) liefert. Das Modul wertet die Antwort mit regulären Ausdrücken aus und übergibt das Ergebnis als Anrufername an die STARFACE-ID-Anzeige (Telefondisplay, UCC-Client, Ruflisten).

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

• Typ: ausgehender HTTP(S)-Aufruf; das Modul ist Client, Ihr System stellt den Endpunkt bereit
• Richtung: STARFACE (Modul) → Drittsystem; ausgelöst bei jeder Rufnummernauflösung, beim manuellen Test („Einstellungen testen") sowie bei der Abfrage der UI-Integration
• Konfigurationsort: Moduloberfläche, Tab Einstellungen, Liste Suchanbieter — eigene Suchanbieter legen Sie im Expertenmodus über das Plus-Symbol an (Resolver-Typ HTTP)
• Methoden: GET (Standard) oder POST (Auswahl im Feld Methode, Expertenmodus)
• Authentifizierung: Keine, Basic, Digest oder Bearer (Auswahl im Feld Authentifizierung)
• TLS: TLSv1.3 und TLSv1.2; Vertrauensbasis ist der Java-Truststore der STARFACE. Die Zertifikatsprüfung lässt sich je Suchanbieter abschalten (Server-Zertifikat prüfen, Expertenmodus); eine separate Hostnamen-Verifizierung findet nicht statt
• Timeout: einstellbar je Suchanbieter, 100–1.500 ms, Standard 700 ms (Details unter Fehlerbehandlung)
• Erreichbarkeit: Ihr Endpunkt muss von der STARFACE aus erreichbar sein; für Cloud-Anlagen mit lokalen Datenquellen steht ein SSH-Tunnel-Konfigurator bereit (seit Modulversion 23.5.25)

Anfrageaufbau

Abfrage-URL und Platzhalter

Die Abfrage-URL hinterlegen Sie im Feld URL der Suchanbieter-Konfiguration. Vor dem Aufruf ersetzt das Modul darin die folgenden Platzhalter (einfache geschweifte Klammern):

Platzhalter	Wird ersetzt durch
{tel}	die aufzulösende Rufnummer im gewählten Rufnummernformat (siehe unten)
{<feldId>}	den Wert des gleichnamigen Konfigurationsfelds des Suchanbieters, z. B. {username}, {password}, {securityToken} — inklusive eventuell definierter Präfixe/Suffixe

Die Ersetzung ist eine reine Zeichenkettenersetzung; anschließend kodiert das Modul Pfad und Query-String URL-konform. Das Pluszeichen einer kanonischen Rufnummer wird dabei nicht prozentkodiert. Viele Web-Frameworks interpretieren + im Query-String als Leerzeichen — wählen Sie in diesem Fall das Rufnummernformat 00xx oder werten Sie den Roh-Query-String aus.

Das Rufnummernformat des Platzhalters {tel} legen Sie je Suchanbieter fest. Nationale Rufnummern konvertiert das Modul anhand der Länderkennung der STARFACE:

Format	Beispielwert
+xx (kanonisch, Standard)	+4972115104230
00xx (international)	004972115104230
0 (national)	072115104230

HTTP-Methode GET

Das Modul ruft die ersetzte URL per GET auf. Die Anfrage trägt browserartige Header (Profil eines Chrome-107-Browsers), unter anderem:

Header	Wert
user-agent	Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36
accept	text/html,application/xhtml+xml,application/xml;q=0.9,…
accept-encoding	gzip, deflate, br
accept-language	de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7
cache-control / pragma	no-cache

Ihr Endpunkt darf die Antwort entsprechend accept-encoding komprimieren (gzip, deflate oder Brotli); HTTP-Weiterleitungen (3xx) folgt das Modul automatisch.

HTTP-Methode POST

Bei der Methode POST sendet das Modul zusätzlich einen festen JSON-Body mit dem Content-Type application/json:

{"query":"<rufnummer>"}

<rufnummer> ist die Rufnummer im gewählten Rufnummernformat. Platzhalter in der URL werden auch bei POST ersetzt. Ein frei gestaltbarer Body ist im Datenmodell vorbereitet, derzeit aber nicht konfigurierbar — Ihr Endpunkt muss das Feld query auswerten.

Authentifizierung

Auswahl	Verhalten
Keine	Anfrage ohne Anmeldedaten
Basic	HTTP Basic Authentication (RFC 7617) mit Benutzername/Kennwort; die Anmeldedaten werden bereits mit der ersten Anfrage gesendet (Preemptive Authentication)
Digest	HTTP Digest Authentication im Challenge-Response-Verfahren: Ihr Endpunkt antwortet mit 401 und WWW-Authenticate, das Modul wiederholt die Anfrage mit Digest-Autorisierung
Bearer	statisches Token aus dem Feld Sicherheitstoken im Header authorization: Bearer <token>

Alternativ können Sie ein Geheimnis (z. B. einen API-Schlüssel) direkt als URL-Bestandteil hinterlegen.

Erwartete Antwort und Auswertung

Ausgewertet werden ausschließlich Antworten mit HTTP-Status 2xx. Der Antwort-Body wird als Text behandelt — das Modul enthält keinen JSON- oder XML-Parser, sondern extrahiert die Daten mit den von Ihnen konfigurierten regulären Ausdrücken. Damit eignet sich jedes textbasierte Format; am robustesten sind flache JSON-Antworten mit eindeutigen Feldnamen. Geben Sie den Zeichensatz explizit an (z. B. Content-Type: application/json; charset=utf-8).

Die Auswertung erfolgt zweistufig (Suchanbieter-Konfiguration → Parser/Ergebnis-Auswertung und STARFACE Feldzuordnungen):

1. Parser: Jeder Parser besteht aus einem Matcher (regulärer Ausdruck, Modus DOTALL/MULTILINE) und einem Formatter. Je Matcher wird der erste Treffer im Antwortdokument verwendet. Im Formatter stehen die Capture-Groups als \1, \2, … bereit; \0 enthält den Gesamttreffer. Das Formatter-Ergebnis wird HTML-dekodiert und getrimmt und steht anschließend als Indexvariable {0}, {1}, … bereit (Reihenfolge der Parser). Über die Option UI stellt ein Parser sein Ergebnis zusätzlich der UI-Integration/Kontext-URL zur Verfügung.
2. Feldzuordnungen: Die Felder Vorname, Nachname und Firma setzen sich aus den Indexvariablen zusammen (z. B. {1} oder {1} ({2})). Das Datenmodell sieht zusätzlich Anzeigenummer und interne Rufnummer vor; die Oberfläche bietet die drei genannten Felder an. Die Darstellung auf Endgeräten und in Ruflisten folgt der ID-Anzeige-Einstellung der STARFACE (Admin → Telefone → ID-Anzeige).

Die Auflösung gilt als erfolgreich, sobald mindestens ein Parser ein nicht-leeres Ergebnis liefert. Erfolgreiche Ergebnisse können je Suchanbieter zwischengespeichert (Caching erfolgreicher Abfragen) und optional in das STARFACE-Adressbuch übernommen werden (Im Adressbuch speichern).

Vollständiges Beispiel

Ihre Anwendung stellt einen Lookup-Endpunkt bereit, der Rufnummern im Format 00xx entgegennimmt. Suchanbieter-Konfiguration:

Einstellung	Wert
Resolver-Typ	HTTP
URL	https://crm.example.com/api/phone-lookup?number={tel}
Rufnummernformat	00xx
Authentifizierung	Bearer, Sicherheitstoken a1b2c3…
Methode	GET

Anfrage des Moduls (Header gekürzt):

GET /api/phone-lookup?number=004972115104230 HTTP/1.1
Host: crm.example.com
authorization: Bearer a1b2c3…
accept-encoding: gzip, deflate, br
user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) … Chrome/107.0.0.0 Safari/537.36

Antwort Ihrer Anwendung:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"firstname":"Erika","lastname":"Musterfrau","company":"Muster GmbH","customer_id":"10815"}

Parser/Ergebnis-Auswertung:

Index	Matcher	Formatter	Bezeichnung
{0}	"firstname":"([^"]*)"	\1	Vorname
{1}	"lastname":"([^"]*)"	\1	Nachname
{2}	"company":"([^"]*)"	\1	Firma

STARFACE Feldzuordnungen: Vorname = {0}, Nachname = {1}, Firma = {2}.

Resultierende Anzeige: Der Anruf von +49 721 15104230 erscheint auf Telefondisplay, im UCC-Client und in den Ruflisten als „Erika Musterfrau" mit der Firma „Muster GmbH" (gemäß ID-Anzeige-Einstellung der STARFACE).

Anwendungsbeispiel

Eine Fachanwendung für den öffentlichen Dienst hält Bürgerdaten, die kein Standard-CRM abbildet. Ein kleiner REST-Endpunkt (GET /api/phone-lookup?number=…) beantwortet die Abfrage aus dem Bestand — Sachbearbeiter sehen schon beim Klingeln, welcher Vorgang anruft, ohne dass Daten die Anwendung verlassen.

Fehlerbehandlung

• Timeout: Der je Suchanbieter konfigurierte Timeout (Standard 700 ms) begrenzt den Verbindungsaufbau. Antwortet Ihr Endpunkt insgesamt langsamer, bricht das Modul die laufende Anfrage nicht ab, protokolliert aber eine Timeout-Warnung im Suchprotokoll. Dimensionieren Sie Ihren Endpunkt so, dass er innerhalb des Timeouts antwortet — die Namensauflösung konkurriert mit der Rufsignalisierung.
• HTTP-Status ≠ 2xx: Die Abfrage gilt als fehlgeschlagen; der Body wird nicht ausgewertet. Bei 4xx ergänzt das Suchprotokoll einen Hinweis (bei öffentlichen Verzeichnissen häufig Browser-Fingerprinting; bei eigenen Endpunkten prüfen Sie Authentifizierung und URL).
• Keine Treffer: Liefern alle Parser ein leeres Ergebnis, gilt die Abfrage als trefferlos („Query did not provide any search results"). Andere aktivierte Suchanbieter und — je nach Einstellung — das STARFACE-Adressbuch greifen als Fallback.
• Mehrere Treffer: Je Matcher wird nur der erste Treffer im Antwortdokument verwendet. Liefern Sie idealerweise genau einen Datensatz je Rufnummer (z. B. serverseitiges LIMIT 1).
• Diagnose: Der Tab Suchanfragen protokolliert jede Auflösung schrittweise (URL, HTTP-Status, Parser-Treffer; im Expertenmodus zusätzlich Redirects und kodierte URI). Über Einstellungen testen lösen Sie eine Testrufnummer gezielt gegen einen Suchanbieter auf.

Versionierung & Kompatibilität

Die Schnittstelle ist nicht explizit versioniert. Den stabilen Vertrag bilden der Platzhalter {tel}, der beschriebene GET-/POST-Aufbau (fester POST-Body mit dem Feld query) sowie die zweistufige Auswertung über Parser und Feldzuordnungen. HTTP-POST und Bearer-Authentifizierung stehen seit Modulversion 23.5.12 zur Verfügung, der SSH-Tunnel-Konfigurator seit 23.5.25. Änderungen und Erweiterungen dokumentieren die Release Notes der jeweiligen Modulversion.